GrepBrowser Documentation

9/15/93, Wednesday

Windows Tech Journal
OOP Alley, October 1993
Greg Voss

Article Title:      What I Learned in Auto Shop
Subject:            Direct Manipulation Tools for Windows
                    Browsers for Source Code Management

Example Programs:   GrepBrowser
                    grep.exe
                    sed.exe

Tools used to       GrepBrowser
build exe's:            Smalltalk/V Windows 2.0, Windows 3.1
                        Borland Resource Workshop
                        Borland C++ 3.1
                    grep and sed
                        Borland C++ 3.1
============================================================

This month's posting is an executable program in binary
form.  The intent is to show a browser that can be
used as a programming tool as well as to show what
a Smalltalk program looks like when distributed
without source.  I have used this browser for a little
over a year to develop and manage source code for large
C, C++, and Lisp projects.

This program is essentially the same as the program
produced by filing in (compiling) the source posted
last month.  I've also posted binary versions of
grep and sed that make it easy to massage output
from various compilers into a format that can be
fed into GrepBrowser.  If you already have versions
of grep and sed, you'll probably want to use your
own as these support only bare bones flag options.
If you use Borland grep, you'll still need sed to
massage the output as Borland output is not standard
Unix (i.e. not designed to be the middle component of
a pipe sequence).


Installation
============

If you have a standard bin or tool directory, copy
all the exe and dll files to that directory.  If
not make a new directory and copy the files there.
This directory must be in your path specifcation
so edit autoexec.bat if you make a new directory.


Using GrepBrowser
=================

GrepBrowser must be invoked with one argument

    gb file

The file is called a 'grep list' file and is
a text file in which each line specifies where
to find text patterns matched by grep.  The
grep list format is shown below.  The most
convenient way to use GrepBrowser is with
Windows' Program Manager. For example, assume
that gb.exe is installed and you have created
a grep list file called tag.grp in the directory
c:\work\compiler.  Create a new program object
in the Program Manager and fill in the fields
as follows.

    Description:        GrepBrowser on tag.grp
    Command Line        gb.exe tag.grp
    Working Directory   c:\work\compiler
    Shortcut Key        (not required)

You can fill in a short cut key if you want.
When you press OK in the Program Item Properties
dialog, the specifications are recorded and
a little nerd icon should appear in the window.
Now double click on the nerd to invoke GrepBrowser.

Note that you do not have to specify a working
directory if you give a fully qualified pathname
for the grep list file:

    gb.exe c:\work\compiler\tag.grp

Technically, the file argument is not required.
However, once a GrepBrowser window is open,
there is no convenient way to change the file
used for the grep list.  You can edit the file
while in the Browser and update the grep list
from a modified version of the same file.  However
you can not select a new grep list file except
from the command line.  This restriction is
easy to modify (see September source code)
but I decided to take time to develop a
more sophisticated command line syntax before
adding menu commands.  There is also some
potential confusion in the menu interface.
Now, the open command will open a regular text
file for editing, so 'Open' is not available
to indcate desire to change the grep list file.

In practice, the current command line syntax
is convenient.  I tend to have a single
grep list file devoted to a given project.
I put tags in the file as markers for grep to
search for.  The only exeption is when I want to
quickly look for a variety of patterns in a set
of files.  In such a case I use file names for
grep output like 00.grp and 01.grp and put
matching program items in the Program Manager.

You can always run GrepBrowser from the
'File / Run' command in Program Manager.  You
can also create an association for 'grp' files
in the File Manager which ties files ending
in '*.grp' to gb.exe.  Then a double click on
a grp file in the File Manager will automatically
invoke a GrepBrowser on the selected file.
(Another example of a Browser using direct
manipulation).



GrepList Format
===============

Each line of the grep list file specifies a
file name, a line number, and text, just like
standard output from grep when the -n flag is used
and more than one file is searched.  It's convenient
to think of each line as a record with three fields or
to think of each line as a specification for
a GrepObject--an actual class in the source.

The following output from grep is typical:

    input.lsp:18:  (defclass c-input-class ()
    parse.lsp:10:  (defclass c-parser-class ()
    scan.lsp:72:   (defclass c-scanner-class ()
    symbol.lsp:11: (defclass lex-symbol ()
    symbol.lsp:27: (defclass symbol-table ()
    test.lsp:1:    (defclass c-input-class ()

In this case the goal was to search for all
class definitions in a set of Lisp files used
to build a C compiler.  The actual grep command 
line was

    grep -n defclass *.lsp >class.grp

Now a GrepBrowser can be opened

    GrepBrowser \work\compiler\class.grp

Or you could set up a Program Item in the
Windows Program Manager as follows:

    Description:        GrepBrowser on Parser Classes
    Command Line        gb.exe class.grp
    Working Directory   c:\work\compiler
    Shortcut Key        (not required)


Searching a Single File
=======================

Note that if grep is used on only one file,
the output will not include the file name.
For example

   grep -n grep notes.txt

produces

    21:    GrepBrowser [grepFile] [searchFile]
    27:(e.g. grepFile: class.grp searchFile: app.h)
    52:grepFile from which the browser should reinitialize
    57:a new grepFile and reinitializing the grepList from
    131:during the parse of the grepList.  The answer
    143:original specification so that modified grepLists


Currently GrepBrowser can't handle lines which do not
include file names.  The mechanisms are in place to
do this and a future release will support this feature.
In the mean time, just give a dummy (non-existent file)
argument to grep:

    grep -n grep notes.txt xxxx >out.grp

produces

    notes.txt:21:    GrepBrowser [grepFile] [searchFile]
    notes.txt:27:(e.g. grepFile: class.grp searchFile: app.h)
    notes.txt:52:grepFile from which the browser should reinitialize
    notes.txt:57:a new grepFile and reinitializing the grepList from
    notes.txt:131:during the parse of the grepList.  The answer
    notes.txt:143:original specification so that modified grepLists

The error message 'GREP.EXE: couldn't open xxxx' 
is sent to stderr (standard error device), not 
to standard output, so it will not interfere 
when output is redirected to out.grp.


Converting Borland C++ Output
=============================

You can use grep and sed in combination
to convert error and warning messages
printed by Borlandc C++ into a format that
can be used by GrepBrowser.  The basic
idea is to direct output to a file
(e.g. bcc.err) and then invoke a batch
file which reads this file and filters
it.  The file bcc2grep.sed contains
two regular expression editing commands:
one for error messages and one for 
warnings.  An example C++ program
(ex1.cpp) will genrate the errors found
in bcc.err.  Both this file and the
converted file created by bcc2grep.bat
are provided with the distribution files
for study.  The following files are all
related to conversion of BC++ output into
a grep list file suitable for GrepBrowser.

    bcc2grep.bat
    ex1.cpp
    bcc.err
    bcc.grp
    bcc2grep.sed


OOP, OOP, and away.